ATOM Documentation

ATOM Menu Bar Icon Design Guide

Overview

This guide defines the visual design specifications for ATOM menu bar companion icons across all supported platforms (macOS, Windows, Linux).

Brand Identity

Primary Colors

• **Primary Gradient:** Cyan (#06B6D4) to Purple (#A855F7)
• **Idle State:** Muted Blue (#3B82F6) at 60% opacity
• **Active States:** Bright Cyan (#22D3EE)
• **Error State:** Red/Orange (#EF4444)
• **Success/Working:** Green (#10B981)

Logo Design

• Stylized "A" lettermark or brain circuit icon
• Represents AI intelligence and neural networks
• Clean, geometric design for scalability

Icon States

1. Idle State

Visual: ATOM logo (stylized "A" or brain circuit)
Color: Muted blue (#3B82F6) at 60% opacity
Animation: Subtle pulse every 3 seconds (breathing effect)
Tooltip: "ATOM AI - Idle"
File: atum-idle.svg/png/ico

2. Thinking/Reasoning State

Visual: ATOM logo with brain circuit glow
Color: Cyan (#06B6D4) with animated ring
Animation: Slow rotation (8s per revolution)
Tooltip: "ATOM AI - Thinking"
Glyph: 🧠 (small badge overlay)
File: atum-thinking.svg/png/ico

3. Working State (General)

Visual: ATOM logo with activity ring
Color: Bright cyan (#22D3EE) with faster pulse
Animation: Quick pulse (1s interval)
Tooltip: "ATOM AI - Working"
File: atum-working.svg/png/ico

4. Working States (Activity-Specific)

Skill Execution

Visual: ATOM logo + 🔧 badge
Color: Bright cyan with gear icon
Animation: Quick pulse
Tooltip: "ATOM AI - Executing Skill"
File: atum-working-skill.svg/png/ico

Communication

Visual: ATOM logo + 💬 badge
Color: Bright cyan with chat icon
Animation: Quick pulse
Tooltip: "ATOM AI - Communicating"
File: atum-working-communication.svg/png/ico

Learning

Visual: ATOM logo + 📚 badge
Color: Bright cyan with book icon
Animation: Quick pulse
Tooltip: "ATOM AI - Learning"
File: atum-working-learning.svg/png/ico

Reasoning

Visual: ATOM logo + 🧠 badge
Color: Cyan with brain icon
Animation: Slow pulse (2s interval)
Tooltip: "ATOM AI - Reasoning"
File: atum-working-reasoning.svg/png/ico

5. Error State

Visual: ATOM logo with warning indicator
Color: Red/Orange (#EF4444)
Animation: None (static to draw attention)
Tooltip: "ATOM AI - Error"
Badge: ⚠️ icon
File: atum-error.svg/png/ico

6. Voice Wake Listening (Future)

Visual: ATOM logo with microphone overlay
Color: Green (#10B981) with audio waveform
Animation: Waveform responds to ambient sound
Tooltip: "ATOM AI - Listening..."
File: atum-voice-listening.svg/png/ico

7. Voice Wake Speaking (Future)

Visual: ATOM logo with speaker icon
Color: Purple (#A855F7) with audio waveform
Animation: Waveform during speech
Tooltip: "ATOM AI - Speaking..."
File: atum-voice-speaking.svg/png/ico

Platform Specifications

macOS Menu Bar

Sizes:
- 16x16px @1x (standard display)
- 32x32px @2x (Retina display)

Format:
- Template images (monochrome with alpha channel)
- Supports light/dark mode automatically
- Use PDF or SVG for vector scalability

Export:
- atum-idle.pdf (template)
- atum-thinking.pdf (template)
- atum-working.pdf (template)
- atum-error.pdf (template)

Windows System Tray

Size:
- 16x16px (standard)
- Optionally 32x32px for high-DPI

Format:
- ICO format with embedded bitmaps
- Supports Windows 11 acrylic effects

Export:
- atum-idle.ico
- atum-thinking.ico
- atum-working.ico
- atum-error.ico

Linux (AppIndicator)

Size:
- 32x32px (standard)
- SVG for scaling on high-DPI displays

Format:
- PNG with transparency
- SVG for vector scaling

Export:
- atum-idle.png (32x32)
- atum-thinking.png (32x32)
- atum-working.png (32x32)
- atum-error.png (32x32)
- atum-idle.svg
- atum-thinking.svg
- atum-working.svg
- atum-error.svg

Design Guidelines

Scalability Rules

1. **16x16px Test:** All icons must be recognizable at 16x16px
2. **Simple Shapes:** Avoid fine details that blur at small sizes
3. **Bold Outlines:** Use minimum 1px stroke at 16x16px
4. **High Contrast:** Ensure visibility on both light and dark backgrounds

Color Usage

1. **Template Images (macOS):** Monochrome with alpha only
2. **Color Icons:** Use brand colors for active states
3. **Error States:** Always use red/orange for visibility
4. **Backgrounds:** Assume both light and dark backgrounds

Animation Principles

1. **Idle:** Subtle breathing (don't distract)
2. **Working:** Fast pulse (show activity)
3. **Thinking:** Slow rotation (show processing)
4. **Error:** Static (draw attention)

Icon Creation Workflow

Step 1: Design (Figma/Sketch)

1. Create base icon at 512x512px
2. Use vector shapes for scalability
3. Test at 16x16px preview

Step 2: Export Variants

# Export from design tool as SVG
# Then use ImageMagick for conversion:

# macOS icons (template)
convert atum-idle.svg -resize 16x16 atum-idle-16.png
convert atum-idle.svg -resize 32x32 atum-idle-32.png

# Create iconset
mkdir AtumIcon.iconset
cp atum-idle-16.png AtumIcon.iconset/icon_16x16.png
cp atum-idle-32.png AtumIcon.iconset/icon_32x32@2x.png
iconutil -c icns AtumIcon.iconset

# Windows ICO
convert atum-idle-16.png atum-idle-32.png atum-idle.ico

# Linux PNG (32x32)
convert atum-idle.svg -resize 32x32 atum-idle.png

# High-DPI Linux (64x64)
convert atum-idle.svg -resize 64x64 atum-idle-64.png

Step 3: Platform-Specific Optimization

1. **macOS:** Create template images (monochrome)
2. **Windows:** Test on Windows 11 with acrylic effects
3. **Linux:** Test on GNOME, KDE, and Ubuntu

Asset Checklist

Required Icons

• [ ] atum-idle (all formats)
• [ ] atum-thinking (all formats)
• [ ] atum-working (all formats)
• [ ] atum-working-skill (all formats)
• [ ] atum-working-communication (all formats)
• [ ] atum-working-learning (all formats)
• [ ] atum-working-reasoning (all formats)
• [ ] atum-error (all formats)
• [ ] atum-voice-listening (all formats) - Future
• [ ] atum-voice-speaking (all formats) - Future

Format Variants

• [ ] SVG (source)
• [ ] PNG (16x16, 32x32, 64x64)
• [ ] ICO (Windows)
• [ ] ICNS/PDF (macOS)

Testing Checklist

Visual Testing

• [ ] Icons visible at 16x16px
• [ ] Icons visible at 32x32px
• [ ] Icons work on light background
• [ ] Icons work on dark background
• [ ] Animations smooth and not distracting
• [ ] All states visually distinct

Platform Testing

• [ ] macOS: Template images work in light/dark mode
• [ ] Windows: Icons visible in system tray
• [ ] Linux: Icons visible in AppIndicator

Integration Testing

• [ ] Icon changes on activity events
• [ ] Icon state machine handles all states
• [ ] No flickering during state transitions
• [ ] Tooltip text matches current state

References

• macOS Human Interface Guidelines - Menu Bar Icons
• Windows 11 Design Guidelines - Icons
• Freedesktop.org Icon Theme Specification

Notes

1. **Placeholder Development:** During initial development, use simple colored squares or circles with text labels (e.g., "AT", "TH", "WK", "ER") to represent different states.

1. **Professional Design:** For production, engage a professional designer or use the AI image generation tool (mcp__4_5v_mcp__analyze_image) to create high-quality icon assets.

1. **Brand Consistency:** All icons should maintain visual consistency with the ATOM brand identity (gradient, colors, typography).

1. **Accessibility:** Ensure color-blind friendly design by using multiple visual cues (shape + color + animation).